/*
 * Copyright 2009 SHOP.COM
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.shop.opensocial.mediated.util;

import com.shop.opensocial.mediated.request.MediatedRequest;
import java.util.List;

/**
 * Used to convert between external representation of an ID and your internal representation (which might be the same).
 * Also used to retrieve friends and groups
 *
 * @author Jordan Zimmerman
 */
public interface UserIdConverter
{
	/**
	 * Return the internal version of the given ID
	 *
	 * @param request request data
	 * @param id ID to convert @return internal version or just return "id" if it's the same
	 * @return converted id
	 * @throws Exception errors
	 */
	public String		convertId(MediatedRequest request, String id) throws Exception;

	/**
	 * Return the list of IDs (internal version) for the given ID (external version)
	 *
	 * @param request request data
	 * @param id external ID
	 * @return list of friends or an empty list if none
	 * @throws Exception errors
	 */
	public List<String>	getFriends(MediatedRequest request, String id) throws Exception;

	/**
	 * Return the list of IDs (internal version) for the given group
	 *
	 * @param request request data
	 * @param group GroupID
	 * @return list of IDs in the group or an empty list if none
	 * @throws Exception errors
	 */
	public List<String>	getGroup(MediatedRequest request, String group) throws Exception;
}
